<html>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<head>
<title>Section 3.3.&nbsp; open Function</title>
<link rel="STYLESHEET" type="text/css" href="images/style.css">
<link rel="STYLESHEET" type="text/css" href="images/docsafari.css">
</head>
<body>
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tr><td><div STYLE="MARGIN-LEFT: 0.15in;"><a href="toc.html"><img src="images/team.gif" width="60" height="17" border="0" align="absmiddle"  alt="Team BBL"></a></div></td>
<td align="right"><div STYLE="MARGIN-LEFT: 0.15in;">
<a href=ch03lev1sec2.html><img src="images/prev.gif" width="60" height="17" border="0" align="absmiddle" alt="Previous Page"></a>
<a href=ch03lev1sec4.html><img src="images/next.gif" width="60" height="17" border="0" align="absmiddle" alt="Next Page"></a>
</div></td></tr></table>
<br><table width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td valign="top"><a name="ch03lev1sec3"></a>
<h3 class="docSection1Title" id="454331-895">3.3. <tt>open</tt> Function</h3>
<p class="docText">A file is opened or created by calling the <tt>open</tt> function.</P>
<a name="inta172"></a><P><table cellspacing="0" class="allBorders" border="1" RULES="none" cellpadding="5"><colgroup><col width="550"></colgroup><thead></thead><tr><TD class="docTableCell" align="left" valign="top"><p class="docText">
<a name="PLID0"></a><div class="v1"><a href="ch03lev1sec3.html#PLID0">[View full width]</a></div><pre>
#include &lt;fcntl.h&gt;

int open(const char *<span class="docEmphItalicAlt">pathname</span>, int <span class="docEmphItalicAlt">oflag</span>, ... /*
<img border="0" width="14" height="9" alt="" align="left" src="images/ccc.gif"> mode_t <span class="docEmphItalicAlt">mode</span>   */ );</pre><BR>
</P></td></TR><TR><TD class="docTableCell" align="right" valign="top"><p class="docText">Returns: file descriptor if OK, 1 on error</p></TD></tr></table></P><BR>
<p class="docText">We show the third argument as <tt>...</tt>, which is the ISO C way to specify that the number and types of the remaining arguments may vary. For this function, the third argument is used only when a new file is being created, as we describe later. We show this argument as a comment in the prototype.</P>
<p class="docText">The <span class="docEmphasis">pathname</span> is the name of the file to open or create. This function has a multitude of options, which are specified by the <span class="docEmphasis">oflag</span> argument. This argument is formed by ORing together one or more of the following constants from the <tt>&lt;fcntl.h&gt;</tt> header:</p>
<P><table cellspacing="0" FRAME="void" RULES="none" cellpadding="5"><colgroup><col width="100"><col width="400"></colgroup><thead></thead><TR><td class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_RDONLY</tt></P></TD><td class="docTableCell" align="left" valign="top"><p class="docText">Open for reading only.</p></td></tr><TR><td class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_WRONLY</tt></P></td><TD class="docTableCell" align="left" valign="top"><p class="docText">Open for writing only.</p></td></tr><tr><td class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_RDWR</tt></p></td><td class="docTableCell" align="left" valign="top"><p class="docText">Open for reading and writing.</p></td></tr></table></p><br>
<blockquote>
<p class="docText">Most implementations define <tt>O_RDONLY</tt> as 0, <tt>O_WRONLY</tt> as 1, and <tt>O_RDWR</tt> as 2, for compatibility with older programs.</p>
</blockquote>
<p class="docText">One and only one of these three constants must be specified. The following constants are optional:</p>
<p><table cellspacing="0" FRAME="void" RULES="none" cellpadding="5"><colgroup><col width="100"><col width="400"></colgroup><thead></thead><tr><TD class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_APPEND</tt></P></td><TD class="docTableCell" align="left" valign="top"><p class="docText">Append to the end of file on each write. We describe this option in detail in <a class="docLink" href="ch03lev1sec11.html#ch03lev1sec11">Section 3.11</a>.</P></TD></tr><TR><TD class="docTableCell" align="left" valign="top"><p class="docText"><a name="idd1e17862"></a><a name="idd1e17865"></a><a name="idd1e17870"></a><a name="idd1e17875"></a><a name="idd1e17880"></a><a name="idd1e17885"></a><a name="idd1e17890"></a><a name="idd1e17895"></a><a name="idd1e17900"></a><a name="idd1e17905"></a><a name="idd1e17910"></a><a name="idd1e17915"></a><a name="idd1e17920"></a><a name="idd1e17923"></a><a name="idd1e17926"></a><a name="idd1e17931"></a><a name="idd1e17936"></a><tt>O_CREAT</tt></P></td><TD class="docTableCell" align="left" valign="top"><p class="docText">Create the file if it doesn't exist. This option requires a third argument to the <tt>open</tt> function, the <span class="docEmphasis">mode</span>, which specifies the access permission bits of the new file. (When we describe a file's access permission bits in <a class="docLink" href="ch04lev1sec5.html#ch04lev1sec5">Section 4.5</a>, we'll see how to specify the <span class="docEmphasis">mode</span> and how it can be modified by the <tt>umask</tt> value of a process.)</p></TD></TR><TR><td class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_EXCL</tt></P></TD><td class="docTableCell" align="left" valign="top"><p class="docText">Generate an error if <tt>O_CREAT</tt> is also specified and the file already exists. This test for whether the file already exists and the creation of the file if it doesn't exist is an atomic operation. We describe atomic operations in more detail in <a class="docLink" href="ch03lev1sec11.html#ch03lev1sec11">Section 3.11</a>.</P></TD></tr><tr><td class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_TRUNC</tt></p></TD><td class="docTableCell" align="left" valign="top"><p class="docText">If the file exists and if it is successfully opened for either write-only or readwrite, truncate its length to 0.</P></td></TR><tr><td class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_NOCTTY</tt></p></td><td class="docTableCell" align="left" valign="top"><p class="docText">If the <span class="docEmphasis">pathname</span> refers to a terminal device, do not allocate the device as the controlling terminal for this process. We talk about controlling terminals in <a class="docLink" href="ch09lev1sec6.html#ch09lev1sec6">Section 9.6</a>.</p></td></tr><tr><td class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_NONBLOCK</tt></p></td><td class="docTableCell" align="left" valign="top"><p class="docText">If the <span class="docEmphasis">pathname</span> refers to a FIFO, a block special file, or a character special file, this option sets the nonblocking mode for both the opening of the file and subsequent I/O. We describe this mode in <a class="docLink" href="ch14lev1sec2.html#ch14lev1sec2">Section 14.2</a>.</p></td></tr></table></p><BR>
<blockquote>
<p class="docText">In earlier releases of System V, the <tt>O_NDELAY</tt> (no delay) flag was introduced. This option is similar to the <tt>O_NONBLOCK</tt> (nonblocking) option, but an ambiguity was introduced in the return value from a read operation. The no-delay option causes a read to return 0 if there is no data to be read from a pipe, FIFO, or device, but this conflicts with a return value of 0, indicating an end of file. SVR4-based systems still support the no-delay option, with the old semantics, but new applications should use the nonblocking option instead.</P>
</blockquote>
<p class="docText">The following three flags are also optional. They are part of the synchronized input and output option of the Single UNIX Specification (and thus POSIX.1):</p>
<P><table cellspacing="0" FRAME="void" RULES="none" cellpadding="5"><colgroup><col width="100"><col width="400"></colgroup><thead></thead><TR><TD class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_DSYNC</tt></p></TD><TD class="docTableCell" align="left" valign="top"><p class="docText">Have each <tt>write</tt> wait for physical I/O to complete, but don't wait for file attributes to be updated if they don't affect the ability to read the data just written.</P></td></TR><tr><TD class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_RSYNC</tt></P></TD><td class="docTableCell" align="left" valign="top"><p class="docText">Have each <tt>read</tt> operation on the file descriptor wait until any pending writes for the same portion of the file are complete.</P></TD></tr><TR><TD class="docTableCell" align="left" valign="top"><p class="docText"><tt>O_SYNC</tt></p></td><td class="docTableCell" align="left" valign="top"><p class="docText">Have each <tt>write</tt> wait for physical I/O to complete, including I/O necessary to update file attributes modified as a result of the <tt>write</tt>. We use this option in <a class="docLink" href="ch03lev1sec14.html#ch03lev1sec14">Section 3.14</a>.</p></TD></tr></table></P><br>
<blockquote>
<p class="docText">The <tt>O_DSYNC</tt> and <tt>O_SYNC</tt> flags are similar, but subtly different. The <tt>O_DSYNC</tt> flag affects a file's attributes only when they need to be updated to reflect a change in the file's data (for example, update the file's size to reflect more data). With the <tt>O_SYNC</tt> flag, data and attributes are always updated synchronously. When overwriting an existing part of a file opened with the <tt>O_DSYNC</tt> flag, the file times wouldn't be updated synchronously. In contrast, if we had opened the file with the <tt>O_SYNC</tt> flag, every <tt>write</tt> to the file would update the file's times before the <tt>write</tt> returns, regardless of whether we were writing over existing bytes or appending to the file.</P>
<p class="docText"><a name="idd1e18148"></a><a name="idd1e18151"></a><a name="idd1e18156"></a><a name="idd1e18163"></a><a name="idd1e18168"></a><a name="idd1e18173"></a><a name="idd1e18178"></a><a name="idd1e18183"></a><a name="idd1e18188"></a><a name="idd1e18193"></a><a name="idd1e18196"></a><a name="idd1e18199"></a><a name="idd1e18202"></a><a name="idd1e18207"></a><a name="idd1e18212"></a><a name="idd1e18217"></a><a name="idd1e18222"></a><a name="idd1e18227"></a><a name="idd1e18230"></a><a name="idd1e18233"></a><a name="idd1e18238"></a><a name="idd1e18241"></a><a name="idd1e18246"></a><a name="idd1e18251"></a>Solaris 9 supports all three flags. FreeBSD 5.2.1 and Mac OS X 10.3 have a separate flag (<tt>O_FSYNC</tt>) that does the same thing as <tt>O_SYNC</tt>. Because the two flags are equivalent, FreeBSD 5.2.1 defines them to have the same value (but curiously, Mac OS X 10.3 doesn't define <tt>O_SYNC</tt>). FreeBSD 5.2.1 and Mac OS X 10.3 don't support the <tt>O_DSYNC</tt> or <tt>O_RSYNC</tt> flags. Linux 2.4.22 treats both flags the same as <tt>O_SYNC</tt>.</p>
</blockquote>
<p class="docText">The file descriptor returned by <tt>open</tt> is guaranteed to be the lowest-numbered unused descriptor. This fact is used by some applications to open a new file on standard input, standard output, or standard error. For example, an application might close standard outputnormally, file descriptor 1and then open another file, knowing that it will be opened on file descriptor 1. We'll see a better way to guarantee that a file is open on a given descriptor in <a class="docLink" href="ch03lev1sec12.html#ch03lev1sec12">Section 3.12</a> with the <tt>dup2</tt> function.</p>
<a name="ch03lev2sec1"></a>
<h4 class="docSection2Title">Filename and Pathname Truncation</h4>
<p class="docText">What happens if <tt>NAME_MAX</tt> is 14 and we try to create a new file in the current directory with a filename containing 15 characters? Traditionally, early releases of System V, such as SVR2, allowed this to happen, silently truncating the filename beyond the 14th character. BSD-derived systems returned an error status, with <tt>errno</tt> set to <tt>ENAMETOOLONG</tt>. Silently truncating the filename presents a problem that affects more than simply the creation of new files. If <tt>NAME_MAX</tt> is 14 and a file exists whose name is exactly 14 characters, any function that accepts a <span class="docEmphasis">pathname</span> argument, such as <tt>open</tt> or <tt>stat</tt>, has no way to determine what the original name of the file was, as the original name might have been truncated.</p>
<p class="docText">With POSIX.1, the constant <tt>_POSIX_NO_TRUNC</tt> determines whether long filenames and long pathnames are truncated or whether an error is returned. As we saw in <a class="docLink" href="ch02.html#ch02">Chapter 2</a>, this value can vary based on the type of the file system.</p>
<blockquote>
<p class="docText">Whether or not an error is returned is largely historical. For example, SVR4-based systems do not generate an error for the traditional System V file system, S5. For the BSD-style file system (known as UFS), however, SVR4-based systems do generate an error.</p>
<p class="docText">As another example, see <a class="docLink" href="ch02lev1sec6.html#ch02fig19">Figure 2.19</a>. Solaris will return an error for UFS, but not for PCFS, the DOS-compatible file system, as DOS silently truncates filenames that don't fit in an 8.3 format.</p>
<p class="docText">BSD-derived systems and Linux always return an error.</p>
</blockquote>
<p class="docText">If <tt>_POSIX_NO_TRUNC</tt> is in effect, <tt>errno</tt> is set to <tt>ENAMETOOLONG</tt>, and an error status is returned if the entire pathname exceeds <tt>PATH_MAX</tt> or any filename component of the pathname exceeds <tt>NAME_MAX</tt>.</p>


<ul></ul></td></tr></table>
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tr><td><div STYLE="MARGIN-LEFT: 0.15in;"><a href="toc.html"><img src="images/team.gif" width="60" height="17" border="0" align="absmiddle"  alt="Team BBL"></a></div></td>
<td align="right"><div STYLE="MARGIN-LEFT: 0.15in;">
<a href=ch03lev1sec2.html><img src="images/prev.gif" width="60" height="17" border="0" align="absmiddle" alt="Previous Page"></a>
<a href=ch03lev1sec4.html><img src="images/next.gif" width="60" height="17" border="0" align="absmiddle" alt="Next Page"></a>
</div></td></tr></table>
</body></html><br>
<table width="100%" cellspacing="0" cellpadding="0"
style="margin-top: 0pt; border-collapse: collapse;"> 
<tr> <td align="right" style="background-color=white; border-top: 1px solid gray;"> 
<a href="http://www.zipghost.com/" target="_blank" style="font-family: Tahoma, Verdana;
 font-size: 11px; text-decoration: none;">The CHM file was converted to HTM by Trial version of <b>ChmD<!--68-->ecompiler</b>.</a>
</TD>
</TR><tr>
<td align="right" style="background-color=white; "> 
<a href="http://www.etextwizard.com/download/cd/cdsetup.exe" target="_blank" style="font-family: Tahoma, Verdana;
 font-size: 11px; text-decoration: none;">Download <b>ChmDec<!--68-->ompiler</b> at: http://www.zipghost.com</a>
</TD></tr></table>
